<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>S3QL::Raw - Low-level interface to the S3DB API</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>

<body style="background-color: white">

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#name">NAME</a></li>
	<li><a href="#synopsis">SYNOPSIS</a></li>
	<li><a href="#description">DESCRIPTION</a></li>
	<li><a href="#keys">Keys</a></li>
	<li><a href="#see_also">SEE ALSO</a></li>
</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>S3QL::Raw - Low-level interface to the S3DB API</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
 <span class="keyword">require</span> <span class="variable">S3QL::Raw</span><span class="operator">;</span>
 <span class="variable">$raw</span> <span class="operator">=</span> <span class="variable">new</span> <span class="variable">S3QL::Raw</span><span class="operator">(</span><span class="operator">{</span><span class="string">my_key</span> <span class="operator">=&gt;</span> <span class="variable">$key</span><span class="operator">}</span><span class="operator">);</span>
 <span class="variable">$raw</span> <span class="operator">=</span> <span class="variable">new</span> <span class="variable">RawS3GL</span><span class="operator">(</span><span class="operator">{</span><span class="string">my_key</span> <span class="operator">=&gt;</span> <span class="variable">$key</span><span class="operator">,</span> <span class="string">my_host</span> <span class="operator">=&gt;</span> <span class="variable">$host</span><span class="operator">}</span><span class="operator">);</span>
 <span class="variable">$q</span> <span class="operator">=</span> <span class="variable">$raw</span><span class="operator">-&gt;</span><span class="keyword">select</span><span class="operator">(</span><span class="variable">$stuff</span><span class="operator">)</span> <span class="operator">.</span> <span class="variable">$raw</span><span class="operator">-&gt;</span><span class="variable">from</span><span class="operator">(</span><span class="variable">$table</span><span class="operator">);</span>
 <span class="variable">$criteria</span> <span class="operator">=</span> <span class="string">''</span><span class="operator">;</span>
 <span class="keyword">foreach</span> <span class="keyword">my</span> <span class="variable">$k</span> <span class="operator">(</span><span class="keyword">keys</span> <span class="variable">%$where</span><span class="operator">)</span> <span class="operator">{</span>
    <span class="variable">$criteria</span> <span class="operator">.=</span> <span class="variable">$raw</span><span class="operator">-&gt;</span><span class="variable">$k</span><span class="operator">(</span><span class="variable">$where</span><span class="operator">-&gt;</span><span class="operator">{</span><span class="variable">$k</span><span class="operator">}</span><span class="operator">);</span>
 <span class="operator">}</span>
 <span class="variable">$q</span> <span class="operator">.=</span> <span class="variable">$raw</span><span class="operator">-&gt;</span><span class="variable">where</span><span class="operator">(</span><span class="variable">$criteria</span><span class="operator">);</span>
</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>The S3QL::Raw class represents a low-level interface to the S3DB API,
which is documented at <a href="http://www.s3db.org">http://www.s3db.org</a>.  The query language
(S3QL) relies on HTTP GET requests to a server linked to an S3DB
database. The basic format of these queries is
<code>http://server/S3qL.php?query=XMLFORMAT</code>.  Here <code>XMLFORMAT</code> stands
in for the precise specification of the query, which is written in a
simplified form of XML.</p>
<p>In order to build these queries conveniently in perl, we have borrowed
the AUTOLOAD implementation from Lincoln Stein's CGI package.  Each
legal tag in the S3DB language is implemented (via AUTOLOAD) as a
method that wraps the arguments to the function in the appropriate
tag.  This the smaple code given in the synopsis produces a <code>select</code>
API call, where <code>$stuff</code> is the regular expression to be matched,
<code>$table</code> is the name of the S3DB table from which the data should be
selected, and <code>%where</code> is a hash containing the selection criteria.</p>
<p>Valid query types are <code>select</code>, <code>insert</code>, <code>edit</code>, and <code>delete</code>.
Currently, the S3DB tables that can be queried using <code>select</code> are:
<code>projects</code>, <code>rules</code>, <code>classes</code>, <code>instances</code>, <code>statements</code>,
<code>users</code>, <code>groups</code>, and <code>keys</code>.  Valid fields and the correct XML
format for all types of queries are documented at the S3DB web site.</p>
<p>
</p>
<hr />
<h1><a name="keys">Keys</a></h1>
<p>An S3DB key, valid for the database accessible through the web host,
must be supplied in order to construct a <code>S3QL::Raw</code> object. See the
instructions at <a href="http://www.s3db.org">http://www.s3db.org</a> to learn how to obtain a key
using the web interface.</p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p>Most of the time, you will want to use the higher-level interface
provided by the <em>S3QL</em> package.</p>

</body>

</html>
